# Набор шаблонов для сайтов Hugo от Radium
## Подключение темы
Настройте [слияние конфигурации](https://gohugo.io/configuration/introduction/#merge-configuration-settings) в `hugo.toml`:
```toml
_merge = 'deep'
```
Это позволяет переопределять параметры, заданные темой, в конфигурации сайта.
## Параметры
Все параметры темы находятся в пространстве имён `radium`:
```text
.Params.radium
```
Параметры сайта доступны через:
```go-html-template
site.Params.radium
```
Параметры также могут быть переопределены для отдельной страницы через front matter.
### Общие параметры
`publisher`
: ссылка на профиль издателя для элементов JSON-LD.
`external_rel`
: значение `rel` по умолчанию для абсолютных ссылок.
### Изображения
Параметры обработки изображений находятся в:
```text
.Params.radium.images
```
`widths`
: набор ширин для генерации адаптивных изображений.
`sizes`
: значение атрибута `sizes` по умолчанию.
`mode`
: режим обработки изображения: `auto`, `lossy` или `lossless`.
Параметры могут задаваться:
1. в конфигурации темы;
2. в конфигурации сайта;
3. во front matter страницы;
4. непосредственно при вызове `image`.
Более специфичное значение имеет приоритет.
## Render hooks
### render-link
Вставляет ссылку с разрешённым набором атрибутов.
Для абсолютных ссылок устанавливает `rel` из настроек сайта или значение по умолчанию:
```text
noopener noreferrer external
```
### render-blockquote
[Вставляет](https://gohugo.io/render-hooks/blockquotes/) блок цитаты с указанием источника и заголовка, а также поддерживает блоки alert.
## Шаблоны
### baseof
Базовый шаблон сайта.
Включает индексирование Pagefind только для элемента `main`.
Для элемента `html` устанавливает язык и направление текста, если направление явно указано в настройках языка.
Подключает partials:
* `head`;
* `header`;
* `footer`.
Блок `main` должен быть переопределён в дочерних шаблонах.
Блок `head` может быть переопределён, если требуется добавить дополнительные элементы в `<head>`.
Если сайт должен публиковать Markdown-представление страниц, `baseof.html` следует переопределить в самом сайте и добавить вызов:
```go-html-template
{{- partial "publish/markdown.html" . -}}
```
Hugo переопределяет `baseof.html` целиком, поэтому в сайт следует скопировать базовый шаблон темы и добавить вызов partial, например в конце шаблона.
## Partials
### attrs
Преобразует `dict` атрибутов в строку HTML-атрибутов.
Обычные значения выводятся в виде:
```html
class="example"
```
Булевы значения обрабатываются как HTML boolean attributes:
* `true` — выводится только имя атрибута;
* `false` — атрибут не выводится.
Например:
```go-html-template
{{ partial "attrs.html" (dict
"class" "video"
"controls" true
"autoplay" false
) }}
```
создаёт:
```html
class="video" controls
```
### pick
Возвращает новый `dict`, содержащий только ключи из переданного массива `allowed`.
Например:
```go-html-template
{{- $attributes := partial "pick.html" (dict
"dict" .Params
"allowed" (slice "class" "id")
) -}}
```
Значения `false`, `0` и пустые строки сохраняются.
### image
Отображает изображение, переданное в параметре `image`.
`image` должен быть Hugo image resource, например полученным через:
```go-html-template
.Resources.Get
resources.Get
resources.GetRemote
```
Для изображений, которые Hugo умеет обрабатывать, partial создаёт адаптивые варианты изображения.
Лесенка размеров определяется параметром `widths`. Если он не передан, используются настройки страницы или сайта из:
```text
radium.images.widths
```
Размеры больше исходного изображения не создаются. Исходная ширина при этом всегда добавляется в `srcset`.
Например, для исходного изображения шириной `4000px` и лесенки:
```text
480 768 1024 1440 1920
```
будут доступны варианты:
```text
480 768 1024 1440 1920 4000
```
Для исходного изображения шириной `1300px`:
```text
480 768 1024 1300
```
#### Lossy-изображения
Для lossy-изображений создаются:
* AVIF;
* WebP.
В HTML используется `<picture>`, где AVIF является предпочтительным форматом, а WebP — fallback.
JPEG автоматически считается lossy.
#### Lossless-изображения
Для lossless-изображений создаётся lossless WebP.
PNG и BMP автоматически считаются lossless.
Для форматов, режим которых нельзя однозначно определить по MIME-типу, следует явно передать:
```text
mode = "lossy"
```
или:
```text
mode = "lossless"
```
#### Исходный формат
Если исходное изображение уже находится в целевом формате и используется в исходном разрешении, оно не перекодируется повторно.
#### SVG и другие необрабатываемые изображения
Изображения, которые Hugo не умеет преобразовывать, передаются без изменения.
SVG дополнительно минифицируется.
Для SVG можно вручную передавать `width` и `height` через `attributes`.
#### Атрибуты
Дополнительные атрибуты `<img>` передаются через `attributes`:
```go-html-template
{{- partial "image.html" (dict
"image" $image
"page" .
"attributes" (dict
"alt" "Описание изображения"
"class" "photo"
"loading" "lazy"
"decoding" "async"
)
) -}}
```
Если `width` и `height` не заданы, partial указывает размеры автоматически, когда Hugo может их определить.
Если передан только один из этих атрибутов, второй вычисляется с сохранением соотношения сторон.
Параметр `sizes` можно передать непосредственно:
```go-html-template
{{- partial "image.html" (dict
"image" $image
"page" .
"sizes" "(max-width: 900px) 100vw, 900px"
) -}}
```
### publish/security-txt
Генерирует ресурс `.well-known/security.txt` по RFC 9116.
Страница с политикой безопасности определяется самим сайтом. Её параметры security.txt находятся в:
```text
.Params.security
```
Стандартный параметр страницы `expiryDate` используется для поля `Expires`.
Partial возвращает Hugo Resource, поэтому публиковать его следует из `layouts/home.html` самого сайта:
```go-html-template
{{- (partial "publish/security-txt.html" (site.GetPage "/security")).Publish -}}
```
Если страница безопасности находится по другому пути, передайте соответствующую страницу в `site.GetPage`.
При многоязычной сборке одного домена вызов следует выполнять только один раз, чтобы разные языковые версии не пытались опубликовать один и тот же файл `.well-known/security.txt`.
### publish/markdown
Публикует Markdown-представление Markdown-страницы рядом с её основным HTML output, заменяя расширение основного файла на `.md`.
Например:
```text
/company/ → company/index.md
/company/security/ → company/security/index.md
/company/security.html → company/security.md
```
Partial предназначен для вызова из переопределённого в самом сайте `baseof.html`:
```go-html-template
{{- partial "publish/markdown.html" . -}}
```
Для поддержки отдачи markdown на nginx добавь в mime.types:
```nginx
text/markdown md;
```
В http секцию nginx.conf:
```nginx
map $http_accept $alternative_index {
default index.html;
~*text/markdown index.md;
}
```
В настройки сайта:
```nginx
index $alternative_index index.html;
add_header Vary Accept always;
```
### logo
Отображает логотип со ссылкой.
Параметры:
`image`
: имя ресурса сайта с логотипом. По умолчанию `img/logo.svg`.
`class`
: класс ссылки, содержащей логотип. По умолчанию `logo`.
`link`
: ссылка логотипа. По умолчанию главная страница с учётом языка.
`alt`
: значение атрибута `alt`. По умолчанию `Logo image`.
### head/favicon
Связывает страницу с найденными favicon.
Для поиска используется маска:
```text
{,**/}favicon.*
```
SVG-файлы минифицируются.
Если Hugo может определить размеры растрового изображения, у `<link>` устанавливается атрибут `sizes`.
### head/apple-touch-icon
Связывает страницу с найденными Apple Touch Icon.
Для поиска используется маска:
```text
{,**/}apple-touch-icon*.png
```
### head/manifest
Связывает страницу с `manifest.json`, находящимся в корне `assets/`.
### assets/require-css
Регистрирует CSS-ресурс компонента для подключения в `<head>`.
Ресурс должен находиться в `assets/`.
Путь передаётся относительно этой директории:
```go-html-template
{{- partial "assets/require-css.html" "css/components/pagination.css" }}
```
Повторная регистрация одного и того же ресурса не приводит к его повторному подключению.
### assets/require-js
Регистрирует JavaScript-ресурс компонента для последующей сборки через `js.Batch` и подключения в `<head>`.
Ресурс должен находиться в `assets/`.
Путь передаётся относительно этой директории:
```go-html-template
{{- partial "assets/require-js.html" "js/pagefind.js" }}
```
Компоненту не требуется самостоятельно вызывать `js.Build`, выполнять минификацию или выводить `<script>`.
### head/css
Подключает основной файл стилей:
```text
css/main.css
```
а также CSS-ресурсы, зарегистрированные компонентами через `assets/require-css`.
### head/js
Подключает основной скрипт:
```text
js/main.js
```
а также JavaScript-ресурсы, зарегистрированные компонентами через `assets/require-js` и собранные через `js.Batch`.
### head/pagefind
Подключает стили и скрипт Pagefind, если окружение не является development.
### head/alternate
Добавляет `<link rel="alternate">` для других языков и форматов страницы.
### head/base
Добавляет в `<head>`:
* `title`;
* `description`;
* canonical URL;
* `meta charset`;
* `viewport`.
### head/social
Добавляет встроенные шаблоны Open Graph и Twitter Cards.
### schema
Подключает JSON-LD-схемы связанных объектов.
В контекст можно передать:
* страницу;
* `dict` с ключами `page` и `schema`.
`schema` может быть строкой или массивом строк.
Пример:
```go-html-template
{{- partial "schema/json-ld.html" . | safeHTML }}
```
С явным указанием схемы:
```go-html-template
{{- partial "schema/json-ld.html" (dict
"page" .
"schema" "BreadcrumbList"
) | safeHTML }}
```
Если в Page Bundle находится файл `<тип>.jsonld`, например:
```text
Person.jsonld
```
соответствующая схема автоматически добавляется в список.
Если в результате список схем пуст, используется [встроенный шаблон Hugo](https://gohugo.io/templates/embedded/#schema).
#### Статья
Для указания `publisher` укажите его в параметрах страницы либо в настройках сайта.
## Shortcodes
### include
Позволяет [вставить](https://gohugo.io/render-hooks/blockquotes/#pageinner-details) другой Markdown-файл в текущий.
Полезно для разделения большой страницы на несколько файлов.
### details
Создаёт `<details>` с возможностью рендеринга внутреннего содержимого как HTML/Markdown.
Аналогичен [стандартному shortcode Hugo](https://gohugo.io/shortcodes/details/#article), но для рендеринга внутреннего содержимого как Markdown следует использовать notation:
```text
{{% details %}}
```
### a
Создаёт ссылку `<a>`.
Поддерживаются атрибуты:
* `href`;
* `title`;
* `rel`;
* `target`;
* `class`;
* `id`;
* `download`;
* `referrerpolicy`;
* `hreflang`;
* `type`;
* `role`;
* `tabindex`;
* `aria-label`;
* `aria-current`;
* `aria-describedby`.
Пример:
```md
{{< a href="/file.pdf" download=true rel="nofollow" >}}
Скачать
{{< /a >}}
```
### section
Создаёт элемент `<section>`.
Поддерживаются атрибуты:
* `class`;
* `id`.
Поддерживает обычную и Markdown-нотацию shortcode.
### video
Создаёт элемент `<video>`.
Поддерживаются обычные атрибуты:
* `class`;
* `poster`;
* `height`;
* `width`;
* `src`;
* `tabindex`;
* `aria-hidden`.
Следующие boolean attributes включены по умолчанию:
* `autoplay`;
* `loop`;
* `muted`;
* `playsinline`;
* `disablepictureinpicture`;
* `disableremoteplayback`.
Их можно отключить, передав boolean `false`.
`controls` по умолчанию отключён и может быть включён значением `true`.
Например:
```md
{{< video
tabindex="-1"
aria-hidden="true"
controls=true
poster="https://peach.blender.org/wp-content/uploads/title_anouncement.jpg?x11217"
>}}
{{< source codecs="avc1.4d002a" >}}
https://archive.org/download/BigBuckBunny_124/Content/big_buck_bunny_720p_surround.mp4
{{< /source >}}
{{< /video >}}
```
Для boolean attributes рекомендуется передавать настоящие булевы значения без кавычек:
```text
controls=true
autoplay=false
```
а не:
```text
controls="true"
autoplay="false"
```
### source
Создаёт `<source>`, предназначенный прежде всего для использования внутри `<video>`.
URL можно передать параметром `src`:
```md
{{< source src="/video.mp4" >}}
```
или внутренним содержимым shortcode:
```md
{{< source >}}
/video.mp4
{{< /source >}}
```
Поддерживаются атрибуты:
* `srcset`;
* `sizes`;
* `media`;
* `width`;
* `height`.
`src`, `type` и `codecs` обрабатываются отдельно.
Если `type` не указан, shortcode пытается определить MIME-тип ресурса автоматически.
При указании `codecs` значение добавляется к `type`, например:
```html
type="video/mp4; codecs=avc1.4d002a"
```
### slot
Сохраняет содержимое шорткода в именованный слот страницы для дальнейшего использования в шаблонах.
Содержимое не попадает в Content, но может быть выведено шаблоном.
```markdown
{{< slot "hero" >}}
# Заголовок Hero секции
Какой угодно **Markdown** внутри hero.
[Подробнее](/privacy/)
{{< /slot >}}
```
